Belgian Amiga Club - ADF Collection/BS1 part 70.zip/BS1 part 70/SuperBase pro v3.02 disk 1.adf/README.DOC

Text File | 1990-04-27 | 26KB | 653 lines

              READ ME : SUPERBASE PROFESSIONAL VERSION 3
              ==========================================

This document contains information about a number of features in
Superbase Professional Version 3 which could not be fully described in
the User Guide.

If you have loaded the Readme file by clicking on its icon, the
controls for viewing the document are as follows: press the space bar
to scroll down the document a page at a time, press Return to scroll
down a line, press B to scroll up a page, press U to scroll up a line.
If you are in the Superbase Text Editor, use the cursor keys or the
scroll bars at the side of the window.

CUT AND PASTE
-------------
The Text and Program Editors now include full Cut and Paste
facilities. In the Text Editor these are both menu options and control
key options, whereas in the Program editor only the control key
options are available. Text may also be moved between fields and
either editor.

Mark Block ^L
-------------
You may mark the block to be operated on either by clicking with the
mouse or with a click-and-drag procedure. In the text editor,
selecting the Edit menu option for Mark Block is the same as
doubleclicking with the mouse, and marks the character under the
cursor as the current block. In the program editor, either the
doubleclick or ^L marks the block.

The click-and-drag procedure allows you to define a block by holding
down the mouse button and moving the mouse. The area of the block is
limited by the borders of the window. If you need to mark a block
larger than the window, use the doubleclick or Ctrl key methods.

Once a character is marked as a block, repeating the Mark Block
operation using any of the three possible methods can have the
following results:

* In front of the first mark, it extends the start of the block.
* After the first mark, it makes a new end to the block.

In the program editor, marking a block in a keyword marks the whole
keyword.

Marked blocks are automatically saved with a Superbase text file.

Clear Block ^Q
--------------
This option removes any marked block from the text.

Cut ^K
------
Selecting Cut removes the marked block and reformats the text. The cut
text is stored on the Clipboard device, and is therefore available to
the Notepad tool.

Copy ^R
-------
Copy stores the current marked block on the Clipboard.

Paste ^P
--------
Paste inserts the text from the Clipboard at the cursor position and
reformats the text.

Cut, Copy and Paste with Field Data
-----------------------------------
The Ctrl key options are all available for use with text fields in
database records and forms. However, it is only possible to mark
complete fields for Cut, Copy and Paste operations. Field data may be
transferred from field to field within a record, as well as to and
from the text and program editors. With Copy, you can store field
contents on the Clipboard and insert them into a new record during
data entry.

Clipboard
---------
Note that the first time you Cut or Copy, the system may request the
Workbench disk so that it can load the Clipboard device software.
Under AmigaDos Version 1.3, you can assign the CLIPS: device.

The contents of the Clipboard are not written to disk until all
programs using the Clipboard device have terminated.


DML COMMANDS AND FUNCTIONS
--------------------------
The following commands and functions are either new or have had their
syntax extended as described.

CALL
The extended syntax for CALL is:

        CALL "command list" [WAIT] [CLOSE]

WAIT causes Superbase to require you to press Return in the Superbase
CLI window before returning. CLOSE closes the Superbase CLI after the
CALL is complete.

If you CLOSE the window, you will need to WAIT first, or there will
not be time to see the CLI output.

See also the information about AREXX, below.


COMMS
For the commands COMMS GET and COMMS INPUT, the syntax has been
slightly altered. The optional parameter TEXT now follows the keywords
GET or INPUT instead of preceding them; i.e. the new syntax is:

     COMMS GET [TEXT] stringvar
     COMMS INPUT [TEXT] stringvar


DIRECTORY
The command DIRECTORY "" is the DML equivalent of the new menu option
System Directory Read. It simply re-reads the current directory, thus
allowing files created with Superbase or the Forms Editor to be listed
within Superbase.

EXISTS
This is a new keyword, which allows a quick check to see whether a
file exists on disk, or whether an index value exists in an index. The
basic syntax is:

        EXISTS (strexpr[,indexfield])

In practice, the file check would often be done in a conditional
statement such as: IF EXISTS ("tempfile") THEN....  The index value
check works on any index of any file, without reading a record. This
would allow you to see whether a specific key exists in any index of
the current file while you are editing that file.

EXISTS ("jones",lastname.ADDRESS) would look up "jones" in the
Lastname index of the Address file, returning True (-1) if "jones"
appeared in it, False (0) if it did not. The function is case
insensitive, unlike LOOKUP. Partial matches return False. Note that if
you combine EXISTS in a validation or calculation with some other
function that does change the record pointer, the effect could be to
overwrite the current record in memory.

FILE
This keyword may now also be used to return the name of the current
Superbase database file. It functions as an operand, as in these
examples:

        IF FILE = "Addresses" THEN....
        a$ = FILE

INDEX
This keyword may now also be used to return the name of the current
index for the current Superbase database file. It functions as an
operand, as in these examples:

        IF INDEX = "Lastname" THEN....
        a$ = FILE

The syntax for INDEX has also been extended to accept a string
expression as an argument:

        INDEX index / [strexpr]

The expression must evaluate to a field name.

MENU
The extended syntax for MENU allows the user to specify an Amiga key
equivalent for any menu option:

        MENU column,item,state[,strexp1][,strexpr2]

strexpr2 must be a single character string containing a keyboard
character.

MOUSE
This new command allows programs to detect the position of the mouse
within the active window, and respond to mouse button input. The
syntax is:

        MOUSE nvar1,nvar2,nvar3

nvar1 returns the state of the mouse button. The possibilities are:

        0  no button has been pressed since the MOUSE command
        3  button is held down now
        1  button has been pressed and released
        2  button has been pressed and released twice within the
           doubleclick period understood by Superbase.

nvar2 returns the X coordinate position of the mouse pointer in
pixels, relative to the top left-hand corner of the window.

nvar3 returns the Y coordinate position of the mouse pointer in
pixels, relative to the top left-hand corner of the window.

Usage: The first call of the MOUSE command informs Superbase of the
variables used to track the mouse position. Subsequent use of the
command will return the current position and state in those specified
variables.  The state variable is continuously updated by Superbase,
however the position variables only reflect the mouse position when
the button last changed state (or the MOUSE command was executed).

Note: The MOUSE command cannot detect the operation of the right or
centre buttons.

The first time you execute MOUSE, you use it as a dummy to set up the
variables and start Superbase tracking MOUSE clicks.

Whenever you read nvar1 it returns the last state of the MOUSE button.
Once read, nvar1 retains its value until another MOUSE event occurs,
so you may want to reset it to 0 with nvar1=0. Since MOUSE does not
actually reset nvar1, you must do this separately.

If nvar1 has the value 1 or 2, nvar2 and nvar3 return the cursor
position when the button was released, so to get the live current
MOUSE pos, you must execute MOUSE as follows:

  WHILE nvar1=3 : MOUSE nvar1,nvar2,nvar3 : [DML commands....]
  : WEND

PANEL
This new command switches the VCR control panel on or off. Syntax:

        PANEL ON / OFF

POSITION
This keyword may now be used as an operand to return the position of
the pointer in a sequential file that is being read by INPUT:

        IF POSITION > x% THEN....

REQUEST
It is now permissible to omit the numeric variable that returns the
outcome of OK or CANCEL selection from REQUEST commands. If the
variable is omitted, two commas should appear next to each other.


SET REQUEST
The SET REQUEST command allows users to define which of the Superbase
confirmation messages, such as "Record has been modified", are
switched off. The syntax is:

        SET REQUEST [ON/OFF]/nexpr

SET REQUEST OFF switches off the three messages that request
confirmation of saving of record, form, or file definition data
following modification. SET REQUEST ON switches the three messages
back on.

The nexpr alternative allows greater precision in switching messages
on and off. nexpr is either a specific number or an OR expression that
evaluates to a number. The basic values are:

     0    All messages on
     1    Record or Form message off
     2    File message off
     4    Text message off
     8    Program message off
     16   End of file message off
     32   Stop OK message off
     255  All messages off

For example, SET REQUEST 8 OR 16 sets both Program and End of file
messages off.

WAIT
The WAIT syntax has been extended to handle waiting for input from
combinations of events.

WAIT MOUSE waits for a mouse click in the data window.
WAIT MENU waits for a selection from a user defined menu.
WAIT KEY waits for a key to be typed while the data window is active.
WAIT PANEL activates the VCR panel and processes user selections until
the stop button is selected.

These options may be combined in any order, for example:

        WAIT MOUSE OR MENU OR KEY

This would put the Superbase task to sleep until any of the specified
occurred. The user program is then responsible for determining which
type of event or events has actually occurred. Note that the OR
keyword is optional.

WAIT COMMS
This special syntax may not be mixed with that described above.
Superbase will poll the RS232 port once a second until the DCD line is
determined to be active, i.e. a connection has been established.
While not actually polling, the Superbase task goes to sleep.


EXECUTABLE CALCULATIONS ON FORMS
--------------------------------
The functionality of this feature has been extended to allow more
powerful form-based applications to run in native mode without the
need for a DML program to drive functions such as data entry. The
executable calculation is, however, an advanced feature requiring an
understanding of the logic of DML commands and of programming
techniques in general.

The main extension is the addition of a direct interface to DML
programs. The commands RUN, CHAIN, LOAD, GOTO and GOSUB are now
performed immediately when encountered during form entry.  Normally
such a command is placed in a read only calculation at the appropriate
point in the field entry order, so that execution takes place when the
cursor "passes through".

RUN, CHAIN and LOAD run the specified program, discarding any program
already in memory.

GOTO immediately exits to the specified label and starts executing the
current program from that point. GOSUB likewise exits to a specified
subroutine, where it should encounter a RETURN statement; control then
returns to the next executable statement in the originating executable
calculation, or the next field or calculation in entry order if the
GOSUB was at the end of the calculation.

END in an executable calculation exits from data entry.

All such commands will execute normally if encountered during form
data entry that has been started with the DML ENTER command. Note that
END does not end the execution of the program.

Within the data entry process, ENTER may be used to switch entry from
one field to another. The normal DML syntax applies, so by naming (or
numbering) a field or a range of fields data entry can redirected in
response to users' actions. Note that the injudicious use of this
feature could produce an infinite logical loop within a form.

Note that the use of executable calculations for operations that are
not self-contained, such as loops that do not start and end within the
same calculation or called subroutine, may result in internal
inconsistencies.

LET calculations and multiple assignments
-----------------------------------------
With this type of form calculation only one LET statement may be used
in each calculation; so you must not define a form calculation
which looks like this:

     LET Amount.invoice = quantity * cost: LET Total.invoice = ...

However, multiple assignments without LET and separated by colons
will be treated as a single ordinary executable calculation.

Auto-execution
--------------
If a read only executable calculation is placed first in the entry
order of a form, it will be executed once only, the first time the
form is loaded. This would allow a program consisting of subroutines
to be loaded automatically for subsequent use during data entry or
editing. If when Superbase has started up with a form there is a
program in memory as a result of such a calculation being auto-
executed, Superbase will not execute the start.sbp program.


AREXX
-----
ARexx is a macro language that allows commands and data to be passed
between applications. Through ARexx, an ARexx program or another
application that supports ARexx can tell Superbase to perform all its
normal functions. Likewise, Superbase can pass command messages to
other applications that are able to receive ARexx messages, such as
the Superplan spreadsheet, or actually run ARexx programs.

The ARexx interface is achieved by two extensions to the syntax of the
CALL command:

        1) CALL "port" EXECUTE strexpr
        2) CALL "port" RETURN strexpr [TO] field / strvar

strexpr must be a string expression consisting of commands
intelligible to the receiving application, maximum length 255
characters. Normally this is equivalent to a stream of characters
typed at the keyboard. Superplan is designed to respond to ARexx
requests, and therefore can serve as a powerful programmable
spreadsheet extension to Superbase itself.

1) This variant is intended to allow other processes to execute
command strings passed from within Superbase. "port" must be a named
ARexx port belonging to another application. The Superbase ARexx port
is called SBPRO. The Superplan ARexx port is called SpRexx. The
default ARexx port is REXX. Note that ARexx is case sensitive.

2) This variant allows the other application to RETURN results to
Superbase in the specified field or string variable. For example,

        CALL "SpRexx" RETURN "c23" TO a$

would store the contents of Superplan's cell c23 in a$.

        CALL "REXX" RETURN "test" TO a$

would attempt to run the ARexx program "test.rexx" and return its exit
code in a$.


Error handling
--------------
If ARexx is unable to complete the requested operation, its error
value will be passed back to Superbase and stored in the ERRNO
operand. The DML program is responsible for checking ERRNO before and
after the ARexx CALL to see whether the action was successful.

If ARexx makes a request to the Superbase ARexx port SBPRO when
Superbase is busy processing, the value -1 will be returned to the
ARexx program or calling application. However, an ARexx program called
from within Superbase can send results back to Superbase by, for
example, setting Superbase variables. Superbase will not return from
the call command until the ARexx process has terminated. To determine
the exit code of an ARexx program, use the second syntax variant,
which returns the exit code to your named variable when it terminates.


COMMUNICATIONS
--------------
Communications on the Amiga are implemented slightly differently from
the description in the User Guide Supplement.

Superbase allows both menu-driven and programmed communications. The
Process Comms menu option allows a number of communications options
for file transfer. Before a file can be transferred, both users should
set up all the parameters in this dialog in the same way. For each of
the following parameters, you must select an option by clicking on its
corresponding button.

Baud rate
---------
Baud rates supported are 300, 1200, 2400 and 9600.

Protocol
--------
Three transfer protocols are supported; XMODEM, XMODEM-CRC and
WXMODEM. If you select WXMODEM and/or XMODEM-CRC for transfer,
Superbase will use it if possible, but is also capable of detecting
whether the receiver is also using WXMODEM, and of "changing gear" by
automatically selecting first XMODEM-CRC and then XMODEM if necessary.
This means that in practice the receiver determines the protocol to be
used.

Options
-------
CHOP removes the padding from the last block of a received file. It
removes zeros, nulls, and ^Z characters. XMODEM always sends files in
128 byte blocks. If the last block is not complete, it is padded out.
Amiga executable files that have been padded out in this way will not
run until the padding is removed. CHOP only applies to received files.

LF->CR Works on transmitted files only, converting Amiga Linefeed
characters (ASCII 10) to Carriage Returns (ASCII 13), enabling text
files created on an Amiga to be read by editors on PCs and other
machines.

AUTO is the same as File Header On/Off for the PC. The header block
will always be transmitted using XMODEM, regardless of the protocol
selected for the actual file transfer.

Transmit/Receive
----------------
As described in the Supplement.

Auto-dial Number
----------------
If your modem has an auto-dial facility, you may enter the receiver's
number in this box.

Comms Initialization Sequence
-----------------------------
You may insert a sequence of up to 28 characters, which will be sent
to the modem when you click on OK, before file transfer begins. The
sequence is stored in the superbase.par file.

Wild Card
---------
You may use the '*' character to represent either a file extension or
a filename. The #? syntax of AmigaDos is not supported.

Cable Connections
-----------------
If you are using a modem, then you should use the cable supplied with
it.  Superbase uses the DCD line from the modem (pin 8) to determine
whether a connection has been established, so make sure this pin is
connected. Also, if your modem has options which change the usage of
the DCD line, make sure that you select the option that causes DCD to
reflect the current connection status.

If you are connecting two computers by a direct RS232 line, they
should be wired up as follows:

        XMIT    2 -------\/------- 2
        RCV     3 -------/\------- 3

        RTS     4 -------\/------- 4
        CTS     5 -------/\------- 5
        DSR   --6                  6--
        GND  |  7 -----------------7  |
        DCD   --8 -------\/------- 8--
        DTR    20 -------/\------- 20


Communications under DML
------------------------
The DML syntax to open the communications channel has changed slightly
from that described in the Supplement. There are now 13 parameters.

OPEN COMMS [USING parameters]

The parameters list is as follows:

param1:   Port number (0 or 1); this is ignored by the Amiga.
param2:   Baud rate (300/1200/2400/9600)
param3:   Parity  (0/1/2)
param4:   Stop bit (either 1 or 2)
param5:   Word length (5/6/7/8)
param6:   Transmit/Receive (1 for Transmit, 0 for Receive)
param7:   File Header  (0 for Off, 1 for On)
param8:   WXMODEM (0 for Off, 1 for Use)
param9:   CRC-XM  (0 for Off, 1 for Use)
param10:  CHOP    (0 for Off, 1 for Use)
param11:  LF/CR   (0 for Conversion, 1 for No conversion)
param12:  Autodial number (text string); Note that Superbase provides
          the 'ATD' sequence automatically.
param13:  Initialization sequence (up to 28 characters, within quotes)

Communications with PCs
-----------------------
Transfer to and from Superbase 4 on the PC can currently only be
accomplished using XMODEM.


MISCELLANEOUS
-------------
* Function Keys. It is now possible to force a function key to execute
its commands even if it is pressed when there is a cursor active in
a field or one of the editors. Simply place the '!' character at the
beginning of the function key string.

* Data Entry. Required (REQ) fields are now checked when you exit from
them as well as when you save the record. Unique indexed (IXU)
fields are likewise checked as soon as data is entered into them as
well as when the data is saved.

* Mail Merge. Superbase now recognizes a double ampersand (&&) in a
text document as an intended single ampersand, so that text such as
"Laurel & Hardy" does not confuse the merging process.

* The SER function is now handled differently by REORGANIZE. Numbers
generated by SER in the new file continue from the highest number in
the old file.

* A Directory Read option has been added to the System menu. This
forces Superbase to re-read the current directory and update its
internal list of the contents.

* A full-size gadget has been added to the title bar for the Text and
Program editors. This provides a quick way of expanding and
contracting the window.

* The DML commands CLEAR, SET, EXECUTE and CALL "port" EXECUTE must be
at the end of their respective program lines.

* If you try to print a line longer than the line length set in
Superbase's Printer options, Superbase will output a Carriage Return
followed by a Line Feed when it reaches the maximum line length.

* Note that you can set a printer initialization sequence from within
Superbase's Set Options dialog. This allows you to set the features
and modes you prefer. The sequence of control codes is sent to the
printer each time you perform a printing operation from within
Superbase. If a sequence is present Superbase does not send the
`Skip over perforation OFF' and `Set page length' codes that are
normally sent when the printer is accessed.

* The output format parameters BF, UL, IT enable you to set different
print styles within a report or in the output from a query. If you
wish to set other printing features, you can do so by using the CHR$
function to insert the appropriate printer control codes. In a
query, you enter these codes in the query fields line. For example,
on some Epson printers, the sequence 27, 14 selects enlarged print,
and the control code 20 turns it off. To output the data for one
field in enlarged print, your query Fields line might look like
this:

  Firstname, Lastname, CHR$(27);CHR$(14);City;CHR$(20), Street

Note that some control codes may be inappropriately interpreted by
the printer device, in which case you should set Print Raw on the
Options requester to bypass the interpretation. Alternatively, you
can use the generic printer device codes published in the Amiga
documentation.

* File Names. Avoid using the characters : ? # / ; or the space
character. When using a file name as an argument to a command such as
OPEN FILE, it must always be inside quotation marks. However, a file
name used to extend a field name, e.g. Name.Customers, need not be
inside quotes, unless it includes non-alphanumeric characters, i.e.
other than a-Z and 0-9. Superbase supplies quotes when necessary
during dialog selections, but if you type a command line in directly
be sure to observe this rule.

* The normal New Line sequence on the Amiga is a CHR$(10) (line feed).
On most other machines and in Superbase, the default New Line sequence
is CHR$(13) CHR$(10) (carriage return, line feed). The CHR$(13) may be
suppressed, for example to achieve compatibility with the ED editor,
by setting RETURN=OFF in the Tool Types list of the Superbase icon,
which may be modified using the Workbench Info option.

* It is now possible to run Superbase by doubleclicking on a program
or form icon. You must create the icon and .info file for a '.sbp' or
'.sbv' file yourself. Demonstration icons are on the data disk. The
.info filename must include `.sbp' as part of the file name; for
example, `myprog.sbp.info'. Consult your Amiga system documentation
for further information on how to do this.

* Tool Types. These are the means of customizing the way in which
Superbase starts up (See User Guide Appendix K). The new option
SCREEN=LACE forces Superbase into Interlace mode on a custom screen.
Tool Types may also be assigned to Superbase form or program icons
(see previous item). The CLI equivalent for LACE is sbpro -l (alphabet
letter, not number).

* Superbase now makes full use of Workbench screens that have been set
to overscan, supporting utilities such as MOREROWS and SCREENSIZER.

* The window title bar indicates the current pathname as well as file.

* Superbase.par file. All communications parameters are stored.

* Labels dialog. There are two new parameters, Top Label Margin and
Label Rows Before FF. These are intended to facilitate label printing
on laser printers. Top Label Margin allows you to specify a vertical
offset as a number of rows. Label Rows Before FF allows you to tell
the printer to perform a form feed after a fixed number of label rows
have been printed. If this parameter is set to zero it is ignored.

* Printer handling. To suppress form feeds issued by some printer
drivers, especially laser printer drivers, the way in which Superbase
handles the printer has been slightly changed. The first time the
printer is used, it is opened; it now remains open until one of the
following events occurs:

     Quit from Superbase
     Termination of a Superbase program
     Selection of the Set Screen menu option
     Any error
     Stop button is clicked or ^C is pressed

Other processes which need the printer may find that it is still in
use by Superbase. If this happens, all that needs to be done is to
click on the Superbase Stop button.